<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Real-time MIDI Support</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="PartOpcodesOverview.html" title="Part II. Opcodes Overview" />
    <link rel="prev" href="PitchTuning.html" title="Tuning Opcodes" />
    <link rel="next" href="MidiInput.html" title="MIDI input" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Real-time MIDI Support</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="PitchTuning.html">Prev</a> </td>
          <th width="60%" align="center">Part II. Opcodes Overview</th>
          <td width="20%" align="right"> <a accesskey="n" href="MidiInput.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="chapter">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="MidiTop"></a>Real-time MIDI Support</h2>
          </div>
        </div>
      </div>
      <p>
    Csound supports realtime MIDI input and output, as well as input from MIDI files. Realtime MIDI input is activated using the <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusUpperM"><em class="citetitle">-M</em></a> (or <span class="emphasis"><em>--midi-device</em></span>=DEVICE) command line flag. You must specify the device number or name after the <span class="emphasis"><em>-M</em></span>. For example to use device number 2, you would use something like:
  </p>
      <div class="literallayout">
        <p>csound -M2 myrtmidi.csd</p>
      </div>
      <p>
    You can find out the available devices by using an out of range device:
  </p>
      <div class="literallayout">
        <p>csound -M99 myrtmidi.csd</p>
      </div>
      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
        <table border="0" summary="Note">
          <tr>
            <td rowspan="2" align="center" valign="top" width="25">
              <img alt="[Note]" src="images/note.png" />
            </td>
            <th align="left">Note</th>
          </tr>
          <tr>
            <td align="left" valign="top">
              <p>
    This will only work if the MIDI module can be accessed by device number. For alsa, you must first find the device name using:
    </p>
              <div class="literallayout">
                <p>cat /proc/asound/cards</p>
              </div>
              <p>
    You must then use something like:
    </p>
              <div class="literallayout">
                <p>csound -+rtmidi=alsa -M hw:3 myrtmidi.csd</p>
              </div>
            </td>
          </tr>
        </table>
      </div>
      <p>
    Realtime MIDI output is activated using <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusUpperQ"><em class="citetitle">-Q</em></a>, using device number or names as shown above.
  </p>
      <p>
    You can also load a MIDI file using the <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusUpperF"><em class="citetitle">-F</em></a> or <span class="emphasis"><em>--midifile</em></span>=FILE command line flag. The MIDI file is read in realtime, and behaves as if it was being performed or recieved in realtime. So the csound program is not aware if MIDI input comes from a MIDI file or directly from a MIDI interface.
  </p>
      <p>
    Once realtime MIDI input and/or output has been activated, opcodes like <a class="link" href="MidiInput.html" title="MIDI input"><em class="citetitle">MIDI Input</em></a> and <a class="link" href="MidiOutput.html" title="MIDI Message Output"><em class="citetitle">MIDI Output</em></a> will have effect.
  </p>
      <p>
    When MIDI input is enabled (with -M or -F), each incoming <span class="emphasis"><em>noteon</em></span> message will generate a note event for an instrument which has the same number as the channel of the event  (This means that MIDI controlled instruments are polyphonic by default, since each note will generate a new instance of the instrument.)
If you have 1 instrument only, Csound works in omni mode, ie. it responds to all channels into that single instrument.
If you have more than one instrument and instrs 1 - 16 , then by default  instr 1 -&gt; chn 1, instr 2 -&gt; chn 2, unless you alter the mapping (see <a class="link" href="massign.html" title="massign"><em class="citetitle">massign</em></a> and <a class="link" href="pgmassign.html" title="pgmassign"><em class="citetitle">pgmassign</em></a> to change this behavior).
If you have more than one instrument, but instr N in between 1 - 16 is missing, then chn N will be routed by default to the lowest order instrument.
  </p>
      <p>
    See the <a class="link" href="MidiInterop.html" title="MIDI/Score Interoperability opcodes"><em class="citetitle">MIDI/Score Interoperability</em></a> opcodes for information on designing instruments which can be used from the score or driven by MIDI.
  </p>
      <p>
    There are several realtime MIDI modules available, you must use the <span class="emphasis"><em>-+rtmidi</em></span> flag (See <a class="link" href="CommandFlagsCategory.html#FlagsCatMinusPlusRtmidi"><em class="citetitle">-+rtmidi</em></a>), to specify the module. The default module is portmidi which provides adecuate MIDI I/O on all platforms, however for improved performance and reliablity some platform specific modules are also provided.
  </p>
      <p>
    Currently the midi modules available are:
  </p>
      <div class="itemizedlist">
        <ul class="itemizedlist" style="list-style-type: disc; ">
          <li class="listitem">
            <p><span class="emphasis"><em>alsa</em></span> - To use the ALSA midi system (Linux only)</p>
          </li>
          <li class="listitem">
            <p><span class="emphasis"><em>winmme</em></span> - To use the windows MME system (Windows only)</p>
          </li>
          <li class="listitem">
            <p><span class="emphasis"><em>portmidi</em></span> - To use the portmidi system (all platforms). This is the default setting.</p>
          </li>
          <li class="listitem">
            <p><span class="emphasis"><em>virtual</em></span> - To use a virtual graphical keyboard (See below) as MIDI input (all platforms)</p>
          </li>
        </ul>
      </div>
      <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
        <table border="0" summary="Tip">
          <tr>
            <td rowspan="2" align="center" valign="top" width="25">
              <img alt="[Tip]" src="images/tip.png" />
            </td>
            <th align="left">Tip</th>
          </tr>
          <tr>
            <td align="left" valign="top">
              <p>When csound runs, it will process the score and then quit. If there are no events in the score, Csound will exit immediately. If you want to use only MIDI events instead of score events, you need to tell Csound to run for a certain amount of time. This can be done with a dummy <a class="link" href="f.html" title="f Statement (or Function Table Statement)"><em class="citetitle">f-statement</em></a> like "f 0 3600".
    </p>
            </td>
          </tr>
        </table>
      </div>
      <div class="section">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="MidiVirtual"></a>Virtual MIDI Keyboard</h2>
            </div>
          </div>
        </div>
        <p>
    </p>
        <div class="mediaobject">
          <img src="images/virtualkeyboard.png" alt="[Virtual MIDI keyboard]" />
          <div class="caption">
            <p>Virtual MIDI keyboard.</p>
          </div>
        </div>
        <p>
  </p>
        <p>
    The virtual MIDI keyboard module (activated using -+rtmidi=virtual on the
    command line flags) provides a way of sending realtime MIDI information to
    Csound without the need of a MIDI device. It can send note information,
    control changes, bank and program changes on a specified channel. The MIDI
    information from the virtual keyboard is processed by Csound in exactly the
    same way as MIDI information that comes from the other MIDI drivers, so if
    your Csound orchestra is designed to work with hardware MIDI devices, this
    will also work.
  </p>
        <p>
    For the device flag (-M), the virtual keyboard uses this to take in the name
    of a keyboard mapping files. Like all MIDI drivers, a device must be given
    to activate the driver. If you would like to just use the default settings
    of the keyboard, simply passing in 0 (i.e. -M0) and the virtual keyboard
    will use its default settings. If instead of the 0 a name of a file is
    given, the keyboard will attempt to load the file as a keyboard mapping. If
    the file could not be opened or read correctly, the default settings will be
    used.
  </p>
        <p>
    Keyboard Mapping files allow the user to customize the name and number of banks
    as well as the name and number of programs per bank.  The following example
    keyboard mapping (named keyboard.map) has inline comments on the file format.
    This file is also available with the Csound source distribution in the
    InOut/virtual_keyboard folder.
  </p>
        <pre class="programlisting">
# Custom Keyboard Map for Virtual Keyboard
# Steven Yi
#
# USAGE
#
# When using the Virtual Keyboard, you can supply a filename for a mapping
# of banks and programs via the -M flag, for example:
#
# csound -+rtmidi=virtual -Mkeyboard.map my_project.csd
#
# INFORMATION ON THE FORMAT
#
# -lines that start with '#' are comments
# -lines that have [] start new bank definitions,
#  the contents are bankNum=bankName, with bankNum=[1,16384]
# -lines following bank statements are program definitions
#  in the format programNum=programName, with programNum=[1,128]
# -bankNumbers and programNumbers are defined in this file
#  starting with 1, but are converted to midi values (starting
#  with 0) when read
#
# NOTES
#
# -if an invalid bank definition is found, all program
#  defintions that follow will be ignored until a new
#  valid bank definition is found
# -if a valid bank is defined by no valid programs found
#  for that bank, it will default to General MIDI program
#  definitions
# -if an invalid program definition is found, it will be
#  ignored

[1=My Bank]
1=My Test Patch 1
2=My Test Patch 2
30=My Test Patch 30

[2=My Bank2]
1=My Test Patch 1(bank2)
2=My Test Patch 2(bank2)
30=My Test Patch 30(bank3)
</pre>
        <p>
    The ten sliders up top are by default set to MIDI Controller number 1-10
    though they can be changed to whatever one wishes to use. The controller
    numbers and values of each slider are set per channel, so one may use
    different settings and values for each channel.
  </p>
        <p>
    By default there are 128 banks and for each bank 128 patches defaulting to
    General Midi names. The MIDI bank standard uses 14-bit resolution to support
    16384 possible banks, but the bank numbers by default are 0-127. To use
    values higher than 127, one should use a custom keyboard map and set the
    desired bank number value for the bank name. The virtual keyboard will
    correctly transmit the bank number as MSB and LSB with controller numbers 0
    and 32.
  </p>
        <p>
    Beyond the input available from interacting with the GUI via mouse, one may
    also trigger off MIDI notes by using the ASCII keyboard when the virtual
    keyboard window is focused. The layout is done much like a tracker and offers
    two octaves and a major third to trigger, starting from Middle-C (MIDI note 60).
    The ASCII keyboard MIDI note values are given in the following table.
  </p>
        <div class="table">
          <a id="idp84564080"></a>
          <p class="title">
            <strong>Table 5. ASCII Keyboard MIDI Note Values</strong>
          </p>
          <div class="table-contents">
            <table summary="ASCII Keyboard MIDI Note Values" border="1">
              <colgroup>
                <col />
                <col />
              </colgroup>
              <thead>
                <tr>
                  <th>Keyboard Key</th>
                  <th>MIDI Value</th>
                </tr>
              </thead>
              <tbody>
                <tr>
                  <td>z</td>
                  <td>60</td>
                </tr>
                <tr>
                  <td>s</td>
                  <td>61</td>
                </tr>
                <tr>
                  <td>x</td>
                  <td>62</td>
                </tr>
                <tr>
                  <td>d</td>
                  <td>63</td>
                </tr>
                <tr>
                  <td>c</td>
                  <td>64</td>
                </tr>
                <tr>
                  <td>v</td>
                  <td>65</td>
                </tr>
                <tr>
                  <td>g</td>
                  <td>66</td>
                </tr>
                <tr>
                  <td>b</td>
                  <td>67</td>
                </tr>
                <tr>
                  <td>h</td>
                  <td>68</td>
                </tr>
                <tr>
                  <td>n</td>
                  <td>69</td>
                </tr>
                <tr>
                  <td>j</td>
                  <td>70</td>
                </tr>
                <tr>
                  <td>m</td>
                  <td>71</td>
                </tr>
                <tr>
                  <td>q</td>
                  <td>72</td>
                </tr>
                <tr>
                  <td>2</td>
                  <td>73</td>
                </tr>
                <tr>
                  <td>w</td>
                  <td>74</td>
                </tr>
                <tr>
                  <td>3</td>
                  <td>75</td>
                </tr>
                <tr>
                  <td>e</td>
                  <td>76</td>
                </tr>
                <tr>
                  <td>r</td>
                  <td>77</td>
                </tr>
                <tr>
                  <td>5</td>
                  <td>78</td>
                </tr>
                <tr>
                  <td>t</td>
                  <td>79</td>
                </tr>
                <tr>
                  <td>6</td>
                  <td>80</td>
                </tr>
                <tr>
                  <td>y</td>
                  <td>81</td>
                </tr>
                <tr>
                  <td>7</td>
                  <td>82</td>
                </tr>
                <tr>
                  <td>u</td>
                  <td>83</td>
                </tr>
                <tr>
                  <td>i</td>
                  <td>84</td>
                </tr>
                <tr>
                  <td>9</td>
                  <td>85</td>
                </tr>
                <tr>
                  <td>o</td>
                  <td>86</td>
                </tr>
                <tr>
                  <td>0</td>
                  <td>87</td>
                </tr>
                <tr>
                  <td>p</td>
                  <td>88</td>
                </tr>
              </tbody>
            </table>
          </div>
        </div>
        <br class="table-break" />
        <p>
      Here's an example of usage of the virtual MIDI keyboard. It uses the file <a class="ulink" href="examples/virtual.csd" target="_top"><em class="citetitle">virtual.csd</em></a>.
 </p>
        <pre class="programlisting">
<span class="csdtag">&lt;CsoundSynthesizer&gt;</span>
<span class="csdtag">&lt;CsOptions&gt;</span>
<span class="comment">; Select audio/midi flags here according to platform</span>
<span class="comment">; Audio out   Audio in     Virtual MIDI    -M0 is needed anyway</span>
-odac           -iadc    -+rtmidi=virtual -M0
<span class="csdtag">&lt;/CsOptions&gt;</span>
<span class="csdtag">&lt;CsInstruments&gt;</span>
<span class="comment">; By Mark Jamerson 2007</span>

<span class="ohdr">sr</span><span class="op">=</span>44100
<span class="ohdr">ksmps</span><span class="op">=</span>10
<span class="ohdr">nchnls</span><span class="op">=</span>2

<span class="ohdr">massign</span> 1,1
<span class="opc">prealloc</span> 1,10

<span class="oblock">instr</span> 1  <span class="comment">;Midi FM synth </span>

inote <span class="opc">cpsmidi</span>
iveloc <span class="opc">ampmidi</span> 10000
idur <span class="op">=</span> 2
    <span class="opc">xtratim</span> 1

kgate <span class="opc">oscil</span> 1,10,2
anoise <span class="opc">noise</span> 100<span class="op">*</span>inote,.99
acps  <span class="opc">samphold</span> anoise,kgate
aosc <span class="opc">oscili</span> 1000,acps,1
aout <span class="op">=</span> aosc

<span class="comment">; Use controller 7 to control volume</span>
kvol <span class="opc">ctrl7</span> 1, 7, 0.2, 1

<span class="opc">outs</span> kvol <span class="op">*</span> aout, kvol <span class="op">*</span> aout

<span class="oblock">endin</span>

<span class="csdtag">&lt;/CsInstruments&gt;</span>
<span class="csdtag">&lt;CsScore&gt;</span>
<span class="stamnt">f</span>0 3600
<span class="stamnt">f</span>1 0 1024 10 1 
<span class="stamnt">f</span>2 0 16 7 1 8 0 8
<span class="stamnt">f</span>3 0 1024 10 1 .5 .6 .3 .2 .5

<span class="stamnt">e</span> 
<span class="csdtag">&lt;/CsScore&gt;</span>
<span class="csdtag">&lt;/CsoundSynthesizer&gt;</span>
</pre>
        <p>
    </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="PitchTuning.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="PartOpcodesOverview.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="MidiInput.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Tuning Opcodes </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> MIDI input</td>
        </tr>
      </table>
    </div>
  </body>
</html>
